home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / lib / c / host / Host.man < prev    next >
Encoding:
Text File  |  1992-06-05  |  4.5 KB  |  133 lines
  1. '\" $Header: /sprite/src/lib/c/host/RCS/Host.man,v 1.5 90/12/13 00:08:00 kupfer Exp Locker: jhh $ SPRITE (Berkeley)
  2. .so \*(]ltmac.sprite
  3. .HS Host lib
  4. .BS
  5. .SH NAME
  6. Host_ByName, Host_ByID, Host_ByNetAddr, Host_ByInetAddr, Host_SetFile,
  7. Host_Start, Host_Next, Host_End \- return information about Sprite machines
  8. .SH SYNOPSIS
  9. .nf
  10. \fB#include <host.h>\fR
  11. .sp
  12. Host_Entry *
  13. \fBHost_ByName\fR(\fIname\fP)
  14. .sp
  15. Host_Entry *
  16. \fBHost_ByID\fR(\fIspriteID\fP)
  17. .sp
  18. Host_Entry *
  19. \fBHost_ByNetAddr\fR(\fIaddrPtr\fP)
  20. .sp
  21. Host_Entry *
  22. \fBHost_ByInetAddr\fR(\fIinetAddr\fP)
  23. .sp
  24. int
  25. \fBHost_SetFile\fR(\fIfileName\fP)
  26. .sp
  27. int
  28. \fBHost_Start\fR()
  29. .sp
  30. Host_Entry *
  31. \fBHost_Next\fR()
  32. .sp
  33. void
  34. \fBHost_End\fR()
  35. .sp
  36. int
  37. \fBHost_Stat\fR(\fIstatPtr\fR)
  38. .SH ARGUMENTS
  39. .AS Net_InetAddress inetAddr
  40. .AP char *name in
  41. The name of a Sprite host for which information is desired.
  42. .AP int spriteID in
  43. The Sprite ID of the host for which information is desired.
  44. .AP Net_Address *addrPtr in
  45. The local network address of the host for which
  46. information is desired. 
  47. .AP Net_InetAddress inetAddr in
  48. The internet address of the host for which information is desired.
  49. .AP char *fileName in
  50. The name of a host-description file.
  51. .AP struct stat *statPtr
  52. Pointer to stat structure for host database file.
  53. .BE
  54. .SH DESCRIPTION
  55. These functions are used to learn about hosts on the local Sprite network.
  56. These functions cause the host description file to be opened.
  57. \fBHost_End()\fR must be called to close the file.
  58. .PP
  59. A Host_Entry structure is defined as follows:
  60. .DS
  61. .ta 1c 2c 3c 4c 5c 6c 7c 8c 9c 10c
  62. typedef struct {
  63.     char        *name;            /* Primary name */
  64.     char        **aliases;        /* Other names */
  65.     int            id;                /* Sprite ID */
  66.     char        *machType;        /* Machine type, i.e "sun3" */
  67.     int            numNets;        /* Number of network interfaces the
  68.                                  * host has. */
  69.     Host_Interface    nets[HOST_MAX_INTERFACES];
  70.                         /* Internet and physical address for
  71.                          * each network interface. */
  72. } Host_Entry;
  73.  
  74. typedef struct Host_Interface {
  75.     Net_InetAddress        inetAddr;        /* Internet address */
  76.     Net_Address            netAddr;        /* Physical address */
  77. } Host_Interface;
  78.  
  79. .DE
  80. The \fInumNets\fR field indicates how many network interfaces the host has.
  81. One entry in the \fInets\fR array will be filled in per interface.
  82. Unused entries will have the network type in \fInetAddr\fI set to
  83. \fBNET_ADDRESS_NONE\fR.
  84. .PP
  85. The Host_Entry structures returned by the routines are statically allocated
  86. and may change on the next call to any \fBHost_\fR procedure.  Be sure to copy
  87. out any information you need before calling a \fBHost_\fR procedure again.
  88. .PP
  89. \fBHost_ByName()\fR returns a Host_Entry based on the name or alias of a host.
  90. .PP
  91. \fBHost_ByID()\fR returns a Host_Entry for the host with the given sprite ID.
  92. .PP
  93. \fBHost_ByNetAddr()\fR returns the Host_Entry for the host with the given
  94. local-area-network address. 
  95. .PP
  96. \fBHost_ByInetAddr()\fR returns the Host_Entry for the host with the given internet
  97. address.
  98. .PP
  99. \fBHost_SetFile()\fR specifies a different host information
  100. file to use (the file normally used
  101. is \fB/etc/spritehosts\fR).
  102. .PP
  103. \fBHost_Start()\fR opens the current host-description file (if it isn't
  104. already open), while \fBHost_End()\fR closes
  105. it.  The \fBHost_By\fR... procedures automatically call \fBHost_Start\fR.
  106. .PP
  107. \fBHost_Next()\fR may be used to step through the current host-description file.
  108. The host-description file must have been opened using \fBHost_Start()\fR or one of the
  109. \fBHost_By\fR functions.
  110. .PP
  111. \fBHost_Stat()\fR is used to get the statistics for the host-description file.
  112. See the \fBstat()\fR man page for details on the stat structure.
  113. \fBHost_Stat()\fR is
  114. useful if you are writing a daemon that wants to do something when
  115. the host-description file is updated. 
  116. The daemon can loop waiting for the modify time of the file to change.
  117. Make sure the host-description file is closed (use \fBHost_End()\fR) before
  118. the daemon waits, otherwise every machine running the daemon will have the
  119. host-description file open, causing lots of consistency traffic.
  120. .SH DIAGNOSTICS
  121. \fBHost_SetFile()\fR,\fBHost_Start()\fR and \fBHost_Stat()\fR
  122. return zero if all went well.  Otherwise
  123. they return -1 and the \fBerrno\fR variable contains additional information
  124. about what error occurred.
  125. \fBHost_Next()\fR returns NULL on end-of-file. \fBHost_ByName()\fR,
  126. \fBHost_ByID()\fR,
  127. \fBHost_ByNetAddr()\fR and \fBHost_ByInetAddr()\fR return NULL if
  128. the given host could not be found.
  129. .SH FILES
  130. /etc/spritehosts    The default host-description file.
  131. .SH KEYWORDS
  132. hostname, internet address, local net, machine type, sprite ID
  133.